Introduction

The Spotflow iOS SDK is a SwiftUI library that allows developers to integrate payment collection functionality into their iOS applications. It provides a simple interface to navigate to a payment screen, handle payment logic, and manage success or failure callbacks using the SpotFlowPaymentUI class.

Beta Release

The iOS SDK is currently a beta release. If you encounter any issues, kindly reach out to our support team at support@spotflow.one.

Project Requirements

To integrate the Spotflow iOS SDK into your project, ensure the following prerequisites are met:

• Xcode 13.0 or later
• iOS 11.0 or higher
• Swift 5.3 or later
• Swift Package Manager (SPM) for dependency management

Installation

Using Swift Package Manager (SPM)

To add SpotFlow - iOS SDK to your project using Xcode or by updating your Package.swift file:

dependencies: [
    .package(url: "https://github.com/Spotflow-One/SpotflowIOS.git", from: "1.0.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: ["Spotflow"]),
]

After adding the dependency, import the Spotflow module where needed:

import Spotflow

Parameters Required by the SDK

Parameter	Type	Description
planId	String	The plan ID (optional).
currency	String	Currency for the payment (e.g., "NGN").
amount	String	Amount to be paid (nullable).
key	String	The API key for authenticating the transaction.
encryptionKey	String	This key is used to encrypt the card for secure transactions.
customerEmail	String	The email address of the customer.
customerName	String	The name of the customer (optional).
customerPhoneNumber	String	The phone number of the customer (optional).
customerId	String	The unique identifier for the customer (optional).
paymentDescription	String	Description of the payment (optional).
appLogo	String	App logo widget (optional).
appName	String	The name of the app (optional).
debugMode	bool	Enable or disable debug mode.

Never expose your key or encryptionKey directly in the app for production. Use a secure server to perform sensitive operations.

Navigating to the Payment Screen

To navigate to the payment screen and initiate a payment process, create an instance of SpotFlowPaymentManager with the required parameters and pass it to SpotFlowPaymentUI.

Example Usage

import SwiftUI
import Spotflow

let config = SpotflowPaymentConfig(
    planId: "plan_001",
    currency: "USD",
    amount: 50.0,
    key: "your_public_key",
    encryptionKey: "your_encryption_key",
    customerEmail: "user@example.com",
    customerName: "Jane Smith",
    customerPhoneNumber: "+123456789",
    customerId: "user_123",
    paymentDescription: "Monthly Subscription",
    appLogo: UIImage(named: "AppLogo"),
    appName: "MyApp",
    debugMode: true
)

Spotflow.shared.startPayment(
    from: self,
    config: config,
    onSuccess: { transactionId, paymentData in
        // Handle success
    },
    onFailure: { errorCode, errorMessage in
        // Handle failure
    }
)

SpotFlowPaymentUI Parameters

• manager: An instance of SpotFlowPaymentManager containing payment and customer information.
• onPaymentSuccess: A closure that gets called when the payment is successful.
• onPaymentFailure: A closure that gets called when the payment fails, with an error as a parameter.

SpotFlowPaymentManager

SpotFlowPaymentManager is a struct that holds all necessary information for a payment transaction.

Properties/Parameters

• merchantId: The merchant ID (String).
• planId: The plan ID (String).
• key: The API key (String).
• encryptionKey: The Encryption key (String).
• customerEmail: The customer's email (String).
• customerName: The customer's name (String, optional).
• customerPhoneNumber: The customer's phone number (String, optional).
• customerId: The customer ID (String, optional).
• paymentDescription: A description of the payment (String, optional).
• appLogo: The logo of the app (Image, optional).
• appName: The name of the app (String, optional).

Handling Error Messages

This SDK provides comprehensive error handling mechanisms to assist in troubleshooting and providing informative feedback to users. Upon encountering an error, detailed error codes and descriptions are returned. By extracting error messages from the response, you can effectively communicate the issue to the user and take appropriate actions. Ensure you implement appropriate error handling mechanisms to provide informative feedback to the user.

Testing

Thoroughly test the integration with different payment scenarios including successful payments, failures, and edge cases to ensure a smooth user experience. Spotflow provides testing helpers that allows you to simulate different payment scenarios.

For your convenience, here are the testing helpers available:

• Card Testing: Test cards can be found here
• Bank Transfer Testing: Test bank transfer scenarios with the testing account details provided during your integration.

These testing helpers help you ensure that your integration handles various payment scenarios effectively before deploying your application to a production environment. It's recommended to thoroughly test your integration with these testing details to provide a reliable payment experience to your users.